docs: Move Height-for-width geometry management virtual methods docs

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 9eec35ce4beb691b23c8cf2231dd9ba5eb908e83..4ced3d99ea38b1747e86f9ecd814997b1758e8a7 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -81,68 +81,13 @@
  *
  * Height-for-width geometry management is implemented in GTK+ by way
  * of five virtual methods:
- * <variablelist>
- *    <varlistentry>
- *       <term>#GtkWidgetClass.get_request_mode()</term>
- *       <listitem>
- *          This allows a widget to tell its parent container whether
- *          it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH
- *          or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode.
- *          %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH means the widget prefers to
- *          have #GtkWidgetClass.get_preferred_width() called and then
- *          #GtkWidgetClass.get_preferred_height_for_width() and is the
- *          default return for unimplemented cases.
- *          However it's important to note (as described below) that any
- *          widget which trades height-for-width must respond properly to
- *          both #GtkSizeRequestModes since it might be queried in either
- *          orientation by its parent container.
- *       </listitem>
- *    </varlistentry>
- *    <varlistentry>
- *       <term>#GtkWidgetClass.get_preferred_width()</term>
- *       <listitem>
- *          This is called by containers to obtain the minimum and
- *          natural width of a widget. A widget will never be allocated
- *          a width less than its minimum and will only ever be allocated
- *          a width greater than the natural width once all of the said
- *          widget's siblings have received their natural widths.
- *          Furthermore, a widget will only ever be allocated a width greater
- *          than its natural width if it was configured to receive extra
- *          expand space from its parent container.
- *       </listitem>
- *    </varlistentry>
- *    <varlistentry>
- *       <term>#GtkWidgetClass.get_preferred_height()</term>
- *       <listitem>
- *          This is called by containers to obtain the minimum and
- *          natural height of a widget.
- *          A widget that does not actually trade any height for width
- *          or width for height only has to implement these two virtual
- *          methods (#GtkWidgetClass.get_preferred_width() and
- *          #GtkWidgetClass.get_preferred_height()).
- *       </listitem>
- *    </varlistentry>
- *    <varlistentry>
- *       <term>#GtkWidgetClass.get_preferred_height_for_width()</term>
- *       <listitem>
- *          This is similar to #GtkWidgetClass.get_preferred_height() except
- *          that it is passed a contextual width to request height for. By
- *          implementing this virtual method it is possible for a #GtkLabel
- *          to tell its parent how much height would be required if the
- *          label were to be allocated a said width.
- *       </listitem>
- *    </varlistentry>
- *    <varlistentry>
- *       <term>#GtkWidgetClass.get_preferred_width_for_height()</term>
- *       <listitem>
- *          This is analogous to #GtkWidgetClass.get_preferred_height_for_width()
- *          except that it operates in the oposite orientation. It's rare that
- *          a widget actually does %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT requests
- *          but this can happen when, for example, a widget or container gets
- *          additional columns to compensate for a smaller allocated height.
- *       </listitem>
- *    </varlistentry>
- * </variablelist>
+ * <itemizedlist>
+ *   <listitem>#GtkWidgetClass.get_request_mode()</listitem>
+ *   <listitem>#GtkWidgetClass.get_preferred_width()</listitem>
+ *   <listitem>#GtkWidgetClass.get_preferred_height()</listitem>
+ *   <listitem>#GtkWidgetClass.get_preferred_height_for_width()</listitem>
+ *   <listitem>#GtkWidgetClass.get_preferred_width_for_height()</listitem>
+ * </itemizedlist>
  *
  * There are some important things to keep in mind when implementing
  * height-for-width and when using it in container implementations.

diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 6e5b020d371556b082f8f206a713dfc279460d14..ee1d571d8ae192c18d63c45121d56236a8293498 100644 (file)
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -131,6 +131,41 @@ struct _GtkWidget
  * @activate_signal: The signal to emit when a widget of this class is
  *   activated, gtk_widget_activate() handles the emission.
  *   Implementation of this signal is optional.
+ * @get_request_mode: This allows a widget to tell its parent container whether
+ *   it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or
+ *   %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode.
+ *   %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH means the widget prefers to have
+ *   #GtkWidgetClass.get_preferred_width() called and then
+ *   #GtkWidgetClass.get_preferred_height_for_width() and is the default
+ *   return for unimplemented cases.
+ *   However it's important to note (as described below) that any widget
+ *   which trades height-for-width must respond properly to both
+ *   #GtkSizeRequestModes since it might be queried in either orientation
+ *   by its parent container.
+ * @get_preferred_height: This is called by containers to obtain the minimum
+ *   and natural height of a widget. A widget that does not actually trade
+ *   any height for width or width for height only has to implement these
+ *   two virtual methods (#GtkWidgetClass.get_preferred_width() and
+ *   #GtkWidgetClass.get_preferred_height()).
+ * @get_preferred_width_for_height: This is analogous to
+ *   #GtkWidgetClass.get_preferred_height_for_width() except that it
+ *   operates in the oposite orientation. It's rare that a widget actually
+ *   does %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT requests but this can happen
+ *   when, for example, a widget or container gets additional columns to
+ *   compensate for a smaller allocated height.
+ * @get_preferred_width: This is called by containers to obtain the minimum
+ *   and natural width of a widget. A widget will never be allocated a width
+ *   less than its minimum and will only ever be allocated a width greater
+ *   than the natural width once all of the said widget's siblings have
+ *   received their natural widths.
+ *   Furthermore, a widget will only ever be allocated a width greater than
+ *   its natural width if it was configured to receive extra expand space
+ *   from its parent container.
+ * @get_preferred_height_for_width: This is similar to
+ *   #GtkWidgetClass.get_preferred_height() except that it is passed a
+ *   contextual width to request height for. By implementing this virtual
+ *   method it is possible for a #GtkLabel to tell its parent how much height
+ *   would be required if the label were to be allocated a said width.
  * @adjust_size_request: Convert an initial size request from a widget's
  *   #GtkSizeRequest virtual method implementations into a size request to
  *   be used by parent containers in laying out the widget.